
\section{Error Bars}
\label{sec:errorbars}

{
\def\pgfplotserror#1{\ensuremath{\epsilon_{#1}}}

An error bar is used to indicate the reliability of a data point. Typically, a
data point is just $(x,y)$. The reliability would be indicated by additional
values, i.e.\@ by means of an error bound $\pgfplotserror{x}$ which
characterizes the difference between the coordinate $x$ provided in the plot
data and the precise value $\tilde x$ (which is unknown). The reliability can
be indicated for both $x$ and $y$ independently (although $y$ might be the
typical candidate). Error bounds can be expressed as \emph{absolute} errors,
i.e.\@ of the form
%
    \begin{equation*}
        \lvert{x-\tilde x}\rvert \le \pgfplotserror{x}, \quad
        \lvert{y-\tilde y}\rvert \le \pgfplotserror{y}
    \end{equation*}
%
where $\tilde x$ and $\tilde y$ are the (unknown) precise values and $x$ and
$y$ are the actual values of the plot. However, they can also be provided
relative to the input values, i.e.\@ of the form
%
    \begin{equation*}
        \frac{\lvert{x-\tilde x}\rvert} {\lvert\tilde x\rvert} \le \pgfplotserror{x},
            \quad
        \frac{\lvert{y-\tilde y}\rvert} {\lvert\tilde y\rvert} \le \pgfplotserror{y}.
    \end{equation*}
%
A relative error of $10\%$ would result in an error value of $0.1$ (relative to
the precise quantity $\tilde y$). Clearly, relative errors are only useful if
the precise value if not zero, i.e.\@ $\tilde x, \tilde y \neq 0$.

\PGFPlots{} allows to provide the ``error values'' for each coordinate
independently. Thus, it may find some value $\pgfplotserror{x}$ and/or
$\pgfplotserror{y}$. Depending on the configuration, it interprets the
encountered value as absolute or relative error. The error value can be the
same for every coordinate, for example if you know that each~$y$-coordinate has
a fixed error of $10\%$. The error value can also be different for every
coordinate in which it is said to be ``explicitly provided''. In fact,
\PGFPlots{} also features \emph{asymmetric} error values, i.e.\@ the lower
bound on the error can be different from the upper bound. Thus, a
two-dimensional data point $(x,y)$ can have up to four distinct error values
which have to be provided by the end-user.

Thus, the end-user has to provide all needed error values and a configuration
to express if these values are to be interpreted as relative or absolute error
and if the values are to be expected explicitly for every data point or if they
are fixed.

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
    \addplot+ [
        error bars/.cd,
            y dir=plus,y explicit,
    ] coordinates {
        (0,0)     +- (0.5,0.1)
        (0.1,0.1) +- (0.05,0.2)
        (0.2,0.2) +- (0,0.05)
        (0.5,0.5) +- (0.1,0.2)
        (1,1)     +- (0.3,0.1)
    };
\end{axis}
\end{tikzpicture}
\end{codeexample}

The preceding example has two keys: |y dir=plus| configures \PGFPlots{} to
\emph{activate} error bars for $y$-coordinates, but only upper bounds. The key
|y explicit| tells \PGFPlots{} to expect \emph{absolute} values in the input
data stream. In our case above, the input data stream is an
|\addplot coordinates| which uses the special error value syntax
|+- |$(\pgfplotserror{x}, \pgfplotserror{y})$, see the
Section~\ref{sec:errorvalues:coords} for details.

It is allowed if the input data contains more error values than needed: our
example above has error values for both $x$ and $y$ and it also contains lower
bounds (since |+-| defines upper- and lower bounds simultaneously).

Consequently, the remaining values can be visualized as well:
%
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
    \addplot+ [
        error bars/.cd,
            y dir=both,y explicit,
            x dir=both,x explicit,
    ] coordinates {
        (0,0)     +- (0.5,0.1)
        (0.1,0.1) +- (0.05,0.2)
        (0.2,0.2) +- (0,0.05)
        (0.5,0.5) +- (0.1,0.2)
        (1,1)     +- (0.3,0.1)
    };
\end{axis}
\end{tikzpicture}
\end{codeexample}

Error bars inherit all drawing options of the associated plot, but they use
their own |error mark| and additional style arguments.

\begin{pgfplotsxykey}{error bars/\x\ dir=\mchoice{none,plus,minus,both} (initially none)}
    The initial configuration \declareandlabel{none} draws no error bars at all
    in the provided direction.

    The configuration \declareandlabel{plus} draws only upper bounds in the
    direction of interest.

    The configuration \declareandlabel{minus} draws only lower bounds in the
    direction of interest.

    The configuration \declareandlabel{both} draws upper and lower bounds in
    the direction of interest.

    In every case, the actual error value and its character (absolute or
    relative) is to be determined by other options (see below). If, for some
    reason, the error value is missing, the error bar is omitted.
\end{pgfplotsxykey}

\begin{pgfplotsxykey}{error bars/\x\ fixed=\marg{value} (initially 0)}
    Provides a common, absolute error $\pgfplotserror x=\text{\meta{value}}$
    for all input coordinates.
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
    \addplot+ [
        error bars/.cd,
            y dir=both,y fixed=0.1,
    ] coordinates {
        (0,0)
        (0.1,0.1)
        (0.2,0.2)
        (0.5,0.5)
        (1,1)
    };
\end{axis}
\end{tikzpicture}
\end{codeexample}

    For linear $x$-axes, the error mark is drawn at $x \pm \pgfplotserror x$
    while for logarithmic $x$-axes, it is drawn at $\log( x \pm \pgfplotserror
    x)$.
\end{pgfplotsxykey}

\begin{pgfplotsxykey}{error bars/\x\ fixed relative=\marg{percent} (initially 0)}
    Provides a common, relative error $\pgfplotserror x = \text{\meta{percent}}
    \cdot x$ for all input coordinates. The argument \meta{percent} is thus
    given relatively to input $x$-coordinates such that $\text{\meta{percent}}
    = 1$ means $100\%$.

    Error marks are thus placed at $x \cdot (1 \pm \pgfplotserror x)$ for
    linear axes and at $\log(x \cdot (1 \pm \pgfplotserror x))$ for logarithmic
    axes. Computations are performed in floating point for linear axis and
    using the identity $\log(x \cdot (1 \pm \pgfplotserror x)) = \log(x) +
    \log( 1 \pm \pgfplotserror x)$ for logarithmic scales.

    The following example shows that fixed error values $\pgfplotserror{x}$ are
    independent of the input values.
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[enlargelimits=false]
    \addplot [red,mark=*] plot [
        error bars/.cd,
            y dir=minus,y fixed relative=1,
            x dir=minus,x fixed relative=1,
            error mark=none,
            error bar style={dotted},
    ] coordinates {
        (0,0) (0.1,0.1) (0.2,0.2)
        (0.5,0.5) (1,1)
    };
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotsxykey}

\begin{pgfplotsxykey}{error bars/\x\ explicit}
    Configures the error bar algorithm to draw $x$-error bars at any input
    coordinate for which user-specified errors are available. Each error is
    interpreted as absolute error, see |x fixed| for details.

    The different input formats of errors are described in
    Section~\ref{sec:errorbar:input}.
\end{pgfplotsxykey}

\begin{pgfplotsxykey}{error bars/\x\ explicit relative}
    Configures the error bar algorithm to draw $x$-error bars at any input
    coordinate for which user-specified errors are available. Each error is
    interpreted as relative error, that means error marks are placed at $x (1
    \pm \text{\meta{value}}(x))$ (works as for |error bars/x fixed relative|).
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{loglogaxis}
    \addplot+ [
        error bars/.cd,
            x dir=both,x fixed relative=0.5,
            y dir=both,y explicit relative,
    ] table [x=x,y=y,y error=error] {
        x       y       error
        32      32      0
        64      64      0
        128     128     0.3
        1024    1024    0.2
        32068   32068   0.6
        64000   64000   0.6
        128000  128000  0.6
    };
\end{loglogaxis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotsxykey}

\begin{pgfplotskey}{error bars/error mark=\meta{marker}}
    Sets an error marker for any error bar. \marg{marker} is expected to be a
    valid plot mark, see Section~\ref{sec:markers}.
    %
\begin{codeexample}[]
\begin{tikzpicture}
    \pgfmathsetseed{42}
\begin{axis}[
    ymajorgrids,
]
    \addplot+ [
        domain=0:180,
        samples=11,
        error bars/.cd,
            y dir=both, y fixed=0.1,
            error mark=diamond*,
    ] {sin(x) + rand*0.1};
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotskey}

\begin{pgfplotskey}{error bars/error mark options=\marg{key-value-list}}
    Sets a key--value list of options for any error mark. This option works
    similarly to the \Tikz{} `|mark options|' key.
\end{pgfplotskey}

\begin{pgfplotskey}{error bars/error bar style=\marg{key-value-list}}
    Appends the argument to `|/pgfplots/every error bar|' which is installed at
    the beginning of every error bar.
\end{pgfplotskey}

\begin{pgfplotscodetwokey}{error bars/draw error bar}
    Allows to change the default drawing commands for error bars. The two
    arguments are
    %
    \begin{itemize}
        \item the source point, $(x,y)$ and
        \item the target point, $(\tilde x,\tilde y)$.
    \end{itemize}
    %
    Both are determined by \PGFPlots{} according to the options described
    above. The default code is
    %
\begin{codeexample}[code only]
\pgfplotsset{
    /pgfplots/error bars/draw error bar/.code 2 args={
        \pgfkeysgetvalue{/pgfplots/error bars/error mark}
            {\pgfplotserrorbarsmark}
        \pgfkeysgetvalue{/pgfplots/error bars/error mark options}
            {\pgfplotserrorbarsmarkopts}
        \draw #1 -- #2 node [pos=1,sloped,allow upside down] {
            \expandafter\tikz\expandafter[\pgfplotserrorbarsmarkopts]{
                \expandafter\pgfuseplotmark\expandafter{\pgfplotserrorbarsmark}
                \pgfusepath{stroke}}
        };
    },
}
\end{codeexample}
\end{pgfplotscodetwokey}


\subsection{Input Formats of Error Coordinates}
\label{sec:errorbar:input}

Error bars with explicit error estimations for single data points require some
sort of input format. This applies to |error bars/x explicit| and
|error bars/x explicit relative|.


\subsubsection{Error Coordinates and Coordinate Lists}
\label{sec:errorvalues:coords}

Error bar coordinates can be read from `|\addplot coordinates|' in which they
are expected after data point as such:
%
\begin{codeexample}[code only]
\addplot coordinates {
    (1,2) +- (0.4,0.2)
    (2,4) +- (1,0)
    (3,5)
    (4,6) +- (0.3,0.001)
}
\end{codeexample}
%
where $(1,2) \pm (0.4,0.2)$ is the first coordinate, $(2,4) \pm (1,0)$ the
second and so forth. The point $(3,5)$ has no error coordinate. The syntax
\declareandlabel{+-} defines \emph{symmetric} error values, i.e.\@ both upper
and lower bound receive the same value.

Alternatively, one can use one of \declareandlabel{-=} and \declareandlabel{+=}
to define asymmetric values:
%
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
    \addplot+ [
        error bars/.cd,
            x dir=both, x explicit,
            y dir=both, y explicit,
    ] coordinates {
        (1.1,0.9) += (0.4,0.2) -= (0.1,0.1)
        (2.7,2)   -= (1,0)
        (3,3)
        (3.8,4.2) +- (0.3,0.2)
    };
\end{axis}
\end{tikzpicture}
\end{codeexample}
%
If multiple items (like multiple |+=|) for one coordinate are specified, the
last one takes precedence.

Keep in mind that these error values are only displayed as error bars if
|x dir| and |y dir| are set appropriately.

The input type |\addplot coordinates| also allows |point meta=explicit|, i.e.\@
values of the form
%
\begin{codeexample}[code only]
\addplot coordinates {(0,0) [4]};
\end{codeexample}
%
This can be combined with error values. However, the point meta value in square
brackets needs to be the last item:
%
\begin{codeexample}[code only]
\addplot coordinates {(0,0) +- (0.1,0.2) [4]};
\end{codeexample}


\subsubsection{Error Coordinates and Table Input}

The `|\addplot table|' format is

\begin{pgfplotsxykeylist}{%
    table/\x\ error=\marg{column name},
    table/\x\ error index=\marg{column index},
    table/\x\ error expr=\marg{math expression}%
}
    These keys define input sources for error bars with explicit error values.

    The |x error| method provides an input column name (or alias), \todosp{I
    think the following text before and after the example are almost the same} the
    |x error index| method provides input column \emph{indices} and
    |x error expr| works just as |table/x expr|: it allows arbitrary
    mathematical expressions which may depend on any number of table columns
    using |\thisrow|\marg{col name}.
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
    \addplot+ [
        error bars/.cd,
            x dir=both, x explicit,
            y dir=both, y explicit,
    ] table [y error=error] {
        x   y   error
        1   0.9 0.4
        2   2.1 0.2
        3   3   0.1
        4   4.2 0.3
    };
\end{axis}
\end{tikzpicture}
\end{codeexample}

    In addition, one can provide column \emph{indices} using
    %
\begin{codeexample}[code only]
\addplot table[x error index=COLINDEX,y error index=COLINDEX]
\end{codeexample}
    %
    These options are used like the `|x|' and `|x index|' options.

    If you need to specify math expressions, you can use |x error expr|:
    %
\begin{codeexample}[code only]
\addplot table[x error expr=\thisrow{errorx}^2]
\end{codeexample}
    %
    This is similar to |x expr|.
    %
\end{pgfplotsxykeylist}

\begin{pgfplotsxykeylist}{%
    table/\x\ error plus=\marg{column name},
    table/\x\ error plus index=\marg{column index},
    table/\x\ error plus expr=\marg{math expression},
    table/\x\ error minus=\marg{column name},
    table/\x\ error minus index=\marg{column index},
    table/\x\ error minus expr=\marg{math expression}%
}
    These keys define input sources for error bars with \emph{asymmetric} error
    values, i.e.\@ different values for upper and lower bounds.

    They are to be used in the same way as |x error|. In fact, |x error| is
    just a style which sets both |x error plus| and |x error minus| to the same
    value.
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
    \addplot+ [
        error bars/.cd,
            x dir=both, x explicit,
            y dir=both, y explicit,
    ] table [
        x error plus=ex+,
        x error minus=ex-,
        y error plus=ey+,
        y error minus=ey-,
    ] {
        x   y   ex+  ey+  ex-  ey-
        1.1 0.9 0.4  0.2  0.1  0.1
        2.7 2   0    0    1    0
        3   3   0    0    0    0
        3.8 4.2 0.3  0.2  0.3  0.2
    };
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotsxykeylist}

}
